home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / LocationManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  10.6 KB  |  366 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        LocationManager.h
  3.  
  4.      Contains:    LocationManager (manage preferences for different physical Locations)
  5.  
  6.      Version:    Technology:    System 7.6
  7.                  Release:    Universal Interfaces 3.0.1
  8.  
  9.      Copyright:    © 1995-1997 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        Please include the the file and version information (from above) with
  12.                  the problem description.  Developers belonging to one of the Apple
  13.                  developer programs can submit bug reports to:
  14.  
  15.                      devsupport@apple.com
  16.  
  17. */
  18. #ifndef __LOCATIONMANAGER__
  19. #define __LOCATIONMANAGER__
  20.  
  21. #ifndef __APPLEEVENTS__
  22. #include <AppleEvents.h>
  23. #endif
  24. #ifndef __COMPONENTS__
  25. #include <Components.h>
  26. #endif
  27. #ifndef __DIALOGS__
  28. #include <Dialogs.h>
  29. #endif
  30. #ifndef __PROCESSES__
  31. #include <Processes.h>
  32. #endif
  33. #ifndef __STANDARDFILE__
  34. #include <StandardFile.h>
  35. #endif
  36.  
  37.  
  38.  
  39. #if PRAGMA_ONCE
  40. #pragma once
  41. #endif
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. #if PRAGMA_IMPORT
  48. #pragma import on
  49. #endif
  50.  
  51. #if PRAGMA_STRUCT_ALIGN
  52.     #pragma options align=mac68k
  53. #elif PRAGMA_STRUCT_PACKPUSH
  54.     #pragma pack(push, 2)
  55. #elif PRAGMA_STRUCT_PACK
  56.     #pragma pack(2)
  57. #endif
  58.  
  59. /* Location Manager API Support -------------------------------------------------------------------- */
  60. /* A Location Token uniquely identifies a Location on a machine... */
  61.  
  62. typedef struct OpaqueALMToken*             ALMToken;
  63. #define kALMNoLocationToken    ((ALMToken)(-1))  // ALMToken of "off" Location...
  64.  
  65. enum {
  66.     kALMLocationNameMaxLen        = 31,                            /* name (actually imposed by file system)... */
  67.     kALMMaxLocations            = 16,                            /* arbitrary limit enforced by Location Manager... */
  68.     kALMNoLocationIndex            = -1                            /* index for the "off" Location (kALMNoLocationToken)... */
  69. };
  70.  
  71. typedef Str31                             ALMLocationName;
  72. /* Returned from ALMConfirmName... */
  73. typedef SInt16                             ALMConfirmChoice;
  74.  
  75. enum {
  76.     kALMConfirmRename            = 1,
  77.     kALMConfirmReplace            = 2
  78. };
  79.  
  80. /* ALMConfirmName dialog item numbers for use in callbacks (ALM 2.0)... */
  81.  
  82.  
  83. enum {
  84.     kALMDuplicateRenameButton    = 1,                            /* if Window refcon is kALMDuplicateDialogRefCon... */
  85.     kALMDuplicateReplaceButton    = 2,
  86.     kALMDuplicateCancelButton    = 3,
  87.     kALMDuplicatePromptText        = 5
  88. };
  89.  
  90.  
  91. enum {
  92.     kALMRenameRenameButton        = 1,                            /* if Window refcon is kALMRenameDialogRefCon... */
  93.     kALMRenameCancelButton        = 2,
  94.     kALMRenameEditText            = 3,
  95.     kALMRenamePromptText        = 4
  96. };
  97.  
  98. /* Refcons of two windows in ALMConfirmName (ALM 2.0)... */
  99.  
  100.  
  101. enum {
  102.     kALMDuplicateDialogRefCon    = FOUR_CHAR_CODE('dupl'),
  103.     kALMRenameDialogRefCon        = FOUR_CHAR_CODE('rnam')
  104. };
  105.  
  106. /* Callback routine for Location awareness (mimics AppleEvents) in non-application code... */
  107.  
  108. typedef CALLBACK_API( void , ALMNotificationProcPtr )(AppleEvent *theEvent);
  109. typedef STACK_UPP_TYPE(ALMNotificationProcPtr)                     ALMNotificationUPP;
  110. enum { uppALMNotificationProcInfo = 0x000000C0 };                 /* pascal no_return_value Func(4_bytes) */
  111. #define NewALMNotificationProc(userRoutine)                     (ALMNotificationUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppALMNotificationProcInfo, GetCurrentArchitecture())
  112. #define CallALMNotificationProc(userRoutine, theEvent)             CALL_ONE_PARAMETER_UPP((userRoutine), uppALMNotificationProcInfo, (theEvent))
  113. /* Notification AppleEvents sent to apps/registered code...  */
  114.  
  115. enum {
  116.     kAELocationChangedNoticeKey    = FOUR_CHAR_CODE('walk'),        /* Current Location changed... */
  117.     kAELocationRescanNoticeKey    = FOUR_CHAR_CODE('trip')        /* Location created/renamed/deleted... */
  118. };
  119.  
  120. /* ALMSwitchToLocation masks... */
  121.  
  122. typedef SInt32                             ALMSwitchActionFlags;
  123.  
  124. enum {
  125.     kALMDefaultSwitchFlags        = 0x00000000,                    /* No special action to take... */
  126.     kALMDontShowStatusWindow    = 0x00000001,                    /* Suppress "switching" window... */
  127.     kALMSignalViaAE                = 0x00000002                    /* Switch by sending Finder AppleEvent... */
  128. };
  129.  
  130. /* Parameters for Get/Put/Merge Location calls... */
  131.  
  132. typedef const OSType *                    ConstALMModuleTypeListPtr;
  133.  
  134. enum {
  135.     kALMAddAllOnSimple            = 0,                            /* Add all single-instance, non-action modules... */
  136.     kALMAddAllOff                = -1                            /* Add all modules but turn them off... */
  137. };
  138.  
  139. /* Item numbers for use in Get/Put/Merge Location filters... */
  140.  
  141.  
  142. enum {
  143.     kALMLocationSelectButton    = 1,
  144.     kALMLocationCancelButton    = 2,
  145.     kALMLocationBalloonHelp        = 3,
  146.     kALMLocationLocationList    = 7,
  147.     kALMLocationLocationNameEdit = 10,
  148.     kALMLocationPromptText        = 11
  149. };
  150.  
  151.  
  152. enum {
  153.     kALMLocationSaveButton        = kALMLocationSelectButton
  154. };
  155.  
  156. /* Location Manager Module API Support ------------------------------------------------------------- */
  157.  
  158. /* ALMGetScriptInfo stuff... */
  159.  
  160.  
  161. enum {
  162.     kALMScriptInfoVersion        = 2                                /* Customarily put in resource for localization... */
  163. };
  164.  
  165. struct ALMScriptManagerInfo {
  166.     SInt16                             version;                    /* Set to kALMScriptInfoVersion... */
  167.     SInt16                             scriptCode;
  168.     SInt16                             regionCode;
  169.     SInt16                             langCode;
  170.     SInt16                             fontNum;
  171.     SInt16                             fontSize;
  172. };
  173. typedef struct ALMScriptManagerInfo ALMScriptManagerInfo;
  174.  
  175. typedef ALMScriptManagerInfo *            ALMScriptManagerInfoPtr;
  176. /*
  177.    Alternate form of ScriptInfo is easier to localize in resources; it is used extensively in
  178.    samples and internally, so....
  179. */
  180. struct ALMAltScriptManagerInfo {
  181.     SInt16                             version;
  182.     SInt16                             scriptCode;
  183.     SInt16                             regionCode;
  184.     SInt16                             langCode;
  185.     SInt16                             fontSize;
  186.     Str63                             fontName;
  187. };
  188. typedef struct ALMAltScriptManagerInfo ALMAltScriptManagerInfo;
  189.  
  190. typedef ALMAltScriptManagerInfo *        ALMAltScriptManagerInfoPtr;
  191. typedef ALMAltScriptManagerInfoPtr *    ALMAltScriptManagerInfoHandle;
  192.  
  193. enum {
  194.     kALMAltScriptManagerInfoRsrcType = FOUR_CHAR_CODE('trip'),
  195.     kALMAltScriptManagerInfoRsrcID = 0
  196. };
  197.  
  198. /* Reboot information used on ALMSetCurrent (input/output parameter)... */
  199.  
  200. typedef UInt32                             ALMRebootFlags;
  201.  
  202. enum {
  203.     kALMNoChange                = 0,
  204.     kALMAvailableNow            = 1,
  205.     kALMFinderRestart            = 2,
  206.     kALMProcesses                = 3,
  207.     kALMExtensions                = 4,
  208.     kALMWarmBoot                = 5,
  209.     kALMColdBoot                = 6,
  210.     kALMShutdown                = 7
  211. };
  212.  
  213. /*
  214.    File types and signatures...
  215.    Note: auto-routing of modules will not be supported for 'thng' files...
  216. */
  217.  
  218.  
  219. enum {
  220.     kALMFileCreator                = FOUR_CHAR_CODE('fall'),        /* Creator of Location Manager files... */
  221.     kALMComponentModuleFileType    = FOUR_CHAR_CODE('thng'),        /* Type of a Component Manager Module file [v1.0]... */
  222.     kALMComponentStateModuleFileType = FOUR_CHAR_CODE('almn'),    /* Type of a CM 'state' Module file... */
  223.     kALMComponentActionModuleFileType = FOUR_CHAR_CODE('almb'),    /* Type of a CM 'action' Module file... */
  224.     kALMCFMStateModuleFileType    = FOUR_CHAR_CODE('almm'),        /* Type of a CFM 'state' Module file... */
  225.     kALMCFMActionModuleFileType    = FOUR_CHAR_CODE('alma')        /* Type of a CFM 'action' Module file... */
  226. };
  227.  
  228. /* Component Manager 'thng' info... */
  229.  
  230.  
  231. enum {
  232.     kALMComponentRsrcType        = FOUR_CHAR_CODE('thng'),
  233.     kALMComponentType            = FOUR_CHAR_CODE('walk')
  234. };
  235.  
  236. /* CFM Modules require a bit of information (replacing some of the 'thng' resource)... */
  237.  
  238.  
  239. enum {
  240.     kALMModuleInfoRsrcType        = FOUR_CHAR_CODE('walk'),
  241.     kALMModuleInfoOriginalVersion = 0
  242. };
  243.  
  244. /* These masks apply to the "Flags" field in the 'thng' or 'walk' resource... */
  245.  
  246.  
  247. enum {
  248.     kALMMultiplePerLocation        = 0x00000001,                    /* Module can be added more than once to a Location... */
  249.     kALMDescriptionGetsStale    = 0x00000002                    /* Descriptions may change though the setting didn't...  */
  250. };
  251.  
  252. /* Misc stuff for older implementations ------------------------------------------------------------ */
  253.  
  254. #if OLDROUTINENAMES
  255. /* Old error codes for compatibility - new names are in Errors interface... */
  256.  
  257. enum {
  258.     ALMInternalErr                = -30049,                        /* use kALMInternalErr */
  259.     ALMLocationNotFound            = -30048,                        /* use kALMLocationNotFoundErr */
  260.     ALMNoSuchModuleErr            = -30047,                        /* use kALMNoSuchModuleErr */
  261.     ALMModuleCommunicationErr    = -30046,                        /* use kALMModuleCommunicationErr */
  262.     ALMDuplicateModuleErr        = -30045,                        /* use kALMDuplicateModuleErr */
  263.     ALMInstallationErr            = -30044,                        /* use kALMInstallationErr */
  264.     ALMDeferSwitchErr            = -30043                        /* use kALMDeferSwitchErr */
  265. };
  266.  
  267. /* Old ALMConfirmName constants... */
  268.  
  269.  
  270. enum {
  271.     ALMConfirmRenameConfig        = kALMConfirmRename,
  272.     ALMConfirmReplaceConfig        = kALMConfirmReplace
  273. };
  274.  
  275. /* Old AppleEvents... */
  276.  
  277.  
  278. enum {
  279.     kAELocationNotice            = kAELocationChangedNoticeKey
  280. };
  281.  
  282. typedef ALMScriptManagerInfo             ALMScriptMgrInfo;
  283. typedef UInt32                             ALMComponentFlagsEnum;
  284. #endif  /* OLDROUTINENAMES */
  285.  
  286. /* Location Manager API ---------------------------------------------------------------------------- */
  287.  
  288. /* The following 7 routines are present if gestaltALMAttr has bit gestaltALMPresent set... */
  289.  
  290. EXTERN_API( OSErr )
  291. ALMGetCurrentLocation            (SInt16 *                index,
  292.                                  ALMToken *                token,
  293.                                  ALMLocationName         name)                                THREEWORDINLINE(0x303C, 0x0600, 0xAAA4);
  294.  
  295. EXTERN_API( OSErr )
  296. ALMGetIndLocation                (SInt16                 index,
  297.                                  ALMToken *                token,
  298.                                  ALMLocationName         name)                                THREEWORDINLINE(0x303C, 0x0501, 0xAAA4);
  299.  
  300. EXTERN_API( OSErr )
  301. ALMCountLocations                (SInt16 *                locationCount)                        THREEWORDINLINE(0x303C, 0x0202, 0xAAA4);
  302.  
  303. EXTERN_API( OSErr )
  304. ALMSwitchToLocation                (ALMToken                 newLocation,
  305.                                  ALMSwitchActionFlags     switchFlags)                        THREEWORDINLINE(0x303C, 0x0403, 0xAAA4);
  306.  
  307. EXTERN_API( OSErr )
  308. ALMRegisterNotifyProc            (ALMNotificationUPP     notificationProc,
  309.                                  const ProcessSerialNumber * whichPSN)                        THREEWORDINLINE(0x303C, 0x0404, 0xAAA4);
  310.  
  311. EXTERN_API( OSErr )
  312. ALMRemoveNotifyProc                (ALMNotificationUPP     notificationProc,
  313.                                  const ProcessSerialNumber * whichPSN)                        THREEWORDINLINE(0x303C, 0x0405, 0xAAA4);
  314.  
  315. EXTERN_API( OSErr )
  316. ALMConfirmName                    (ConstStr255Param         message,
  317.                                  Str255                 theName,
  318.                                  ALMConfirmChoice *        choice,
  319.                                  ModalFilterUPP         filter)                                THREEWORDINLINE(0x303C, 0x0806, 0xAAA4);
  320.  
  321. /* The following 3 routines are present if gestaltALMAttr has bit gestaltALMHasSFLocation set... */
  322.  
  323. EXTERN_API( OSErr )
  324. ALMPutLocation                    (ConstStr255Param         prompt,
  325.                                  ALMLocationName         name,
  326.                                  SInt16                 numTypes,
  327.                                  ConstALMModuleTypeListPtr  typeList,
  328.                                  ModalFilterYDUPP         filter,
  329.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0B07, 0xAAA4);
  330.  
  331. EXTERN_API( OSErr )
  332. ALMGetLocation                    (ConstStr255Param         prompt,
  333.                                  ALMLocationName         name,
  334.                                  ModalFilterYDUPP         filter,
  335.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0808, 0xAAA4);
  336.  
  337. EXTERN_API( OSErr )
  338. ALMMergeLocation                (ConstStr255Param         prompt,
  339.                                  ALMLocationName         name,
  340.                                  SInt16                 numTypes,
  341.                                  ConstALMModuleTypeListPtr  typeList,
  342.                                  ModalFilterYDUPP         filter,
  343.                                  void *                    yourDataPtr)                        THREEWORDINLINE(0x303C, 0x0B09, 0xAAA4);
  344.  
  345.  
  346. #if PRAGMA_STRUCT_ALIGN
  347.     #pragma options align=reset
  348. #elif PRAGMA_STRUCT_PACKPUSH
  349.     #pragma pack(pop)
  350. #elif PRAGMA_STRUCT_PACK
  351.     #pragma pack()
  352. #endif
  353.  
  354. #ifdef PRAGMA_IMPORT_OFF
  355. #pragma import off
  356. #elif PRAGMA_IMPORT
  357. #pragma import reset
  358. #endif
  359.  
  360. #ifdef __cplusplus
  361. }
  362. #endif
  363.  
  364. #endif /* __LOCATIONMANAGER__ */
  365.  
  366.